extract-files

What is extract-files?

The extract-files package is designed to extract files from a JavaScript object tree so they can be uploaded via a multipart request. It is commonly used in applications that need to handle file uploads, especially in the context of GraphQL operations.

What are extract-files's main functionalities?

Extract files from an object

This feature allows you to extract files from an object, which is useful when preparing files for upload. The `extractFiles` function takes an object and a path to traverse within the object to find files. It returns an object with the extracted files and a clone of the original object with files replaced by null.

{"operation": "const { extractFiles } = require('extract-files');\nconst file = new File(['content'], 'file.txt', { type: 'text/plain' });\nconst operation = { variables: { file } };\nconst { files, clone } = extractFiles(operation, 'variables');"}

Support for FileList and Map objects

The package can handle `FileList` objects, which are typically obtained from file input elements, and `Map` objects. It can extract files from these complex structures, making it versatile for various file upload scenarios.

{"operation": "const { extractFiles } = require('extract-files');\nconst fileList = document.querySelector('input[type=file]').files;\nconst operation = { variables: { files: fileList } };\nconst { files, clone } = extractFiles(operation, 'variables');"}

Other packages similar to extract-files

form-data

The form-data package allows you to create `multipart/form-data` streams to submit files and values via HTTP. It can be used to simulate a form submission with file uploads, similar to extract-files, but it is more focused on constructing the form data itself rather than extracting files from an existing object structure.

busboy

Busboy is a Node.js module for parsing incoming HTML form data, including file uploads. It differs from extract-files in that it is used on the server side to process file uploads, whereas extract-files is typically used on the client side to prepare files for upload.

multer

Multer is a Node.js middleware for handling `multipart/form-data`, primarily used for uploading files. It is similar to busboy but is designed to be used with Express applications. Unlike extract-files, multer is not about extracting files from an object but rather about handling file uploads on the server side.

README

extract-files

A function to recursively extract files and their object paths within a value, replacing them with null in a deep clone without mutating the original value. FileList instances are treated as File instance arrays. Files are typically File and Blob instances.

Used by GraphQL multipart request spec client implementations such as graphql-react and apollo-upload-client.

Installation

To install with npm, run:

npm install extract-files

See the documentation for the function extractFiles to get started.

Requirements

• Node.js: ^12.22.0 || ^14.17.0 || >= 16.0.0
• Browsers: > 0.5%, not OperaMini all, not IE > 0, not dead

Exports

These ECMAScript modules are published to npm and exported via the package.json exports field:

• extractFiles.mjs
• isExtractableFile.mjs

extractFiles.mjs

Export default

Function extractFiles — Recursively extracts files and their object paths within a value, replacing them with null in a deep clone without mutating the original value. FileList instances are treated as File instance arrays.

Type parameters

1. Extractable: any — Extractable file type.

Parameters

1. value: unknown — Value to extract files from. Typically an object tree.
2. isExtractable: (value: unknown) => value is Extractable — Matches extractable files. Typically isExtractableFile.
3. path ?: ObjectPath — Prefix for object paths for extracted files. Defaults to "".

Returns

Extraction<Extractable> — Extraction result.

Example 1

Extracting files from an object.

For the following:

import extractFiles from "extract-files/extractFiles.mjs";
import isExtractableFile from "extract-files/isExtractableFile.mjs";

const file1 = new File(["1"], "1.txt", { type: "text/plain" });
const file2 = new File(["2"], "2.txt", { type: "text/plain" });
const value = {
  a: file1,
  b: [file1, file2],
};

const { clone, files } = extractFiles(value, isExtractableFile, "prefix");

value remains the same.

clone is:

{
  "a": null,
  "b": [null, null]
}

files is a Map instance containing:

Key	Value
file1	["prefix.a", "prefix.b.0"]
file2	["prefix.b.1"]

Type Extraction

object — An extraction result.

Type parameters

1. Extractable ?: any — Extractable file type. Defaults to unknown.

Properties

• clone: unknown — Clone of the original value with files recursively replaced with null.
• files: Map<Extractable, Array<ObjectPath>> — Extracted files and their object paths within the original value.

Type ObjectPath

string — String notation for the path to a node in an object tree.

See

• object-path on npm.

Example 1

An object path for object property a, array index 0, object property b:

a.0.b

isExtractableFile.mjs

Export default

Function isExtractableFile — Checks if a value is an extractable file.

Parameters

1. value: unknown — Value to check.

Returns

value is ExtractableFile — Is the value an extractable file.

Type ExtractableFile

File | Blob — An extractable file.